Parent | Child | Previous | Next

JavaScript

{dialog.object}saveListEdits Method

IN THIS PAGE

Synchronizing Data Using pullSync
Example: Setting Request Timeouts and Custom Error Handlers
Example: Defining Custom Callback Functions when saveListEdits fails
Example: Customizing the Unsaved Changes Message

Syntax

{dialog.object}.saveListEdits(listId [,options]);

Arguments

listId

A key for saved data entered into the repository.

optionsjson object

A JSON object specifying optional parameters. Available options include:

ajaxobject

Settings for adding custom handling when the sync fails because the device is offline or the server is unresponsive (does not respond before the request times out.) Settings include:

amountofdatatosendstring: Default = ".1MB".The amount of data to send to the server. Used if a speed test is performed.
checkifserveravailableboolean: Default = true. Specifies whether or not to check if the application server is available before making an Ajax callback to save the List edits.
maxspeedtestdurationnumber: Default = 300. The amount of time to wait in milliseconds for a response from the server during a speed test. If no response is received from the server in the specified duration, the speed test fails.
onAjaxFailfunction: JavaScript function to call when an Ajax callback to save the List edits fails (for example, if the server took longer to respond than the length of the timeout).
onDeviceOfflinefunction: JavaScript function to call when the device is offline.
onPoorConnectionfunction: JavaScript function to call when a speed test fails.
onServerNotAvailablefunction: JavaScript function to call when the server is not available, e.g. the server is offline or cannot be reached over the network.
performspeedtestboolean: Default = false. Specifies if a speed test should be performed before making the Ajax callback. The speed test is useful if you want to prevent users from trying to synchronize List data in they have a poor internet connection. The speed test is performed by sending a specified amount of data to the server and measuring how long it takes before the server responds.
serveravailabletimeoutnumber: Default = 4000. The amount of time to wait in milliseconds for the server to respond.
timeOutnumber: Duration of the timeout before the request is considered to have failed.
retryCountnumber: Number of times to retry the synchronize action in case of a timeout. Each retry increases the timeout. A maximum of 3 retries are allowed.

allChildRecordsboolean

Default = false. By default, if a List has a child List, only the dirty child records are submitted when data is submitted. If this flag is set to true, then all child records (dirty and not dirty) are submitted to the server.

allParentListsboolean

Can be true or false. If true, parent records will be submitted for a List control that has a parent List.

batchSizenumber

Overrides the batch size property for the List control. Specifies the number of records to submit when data is synchronized using batches.

checkForMediaFilesboolean

If true, new or updated media files will be synchronized. For Cordova applications with media files.

chunkedobject

An object that defines whether or not chunked responses should be sent while saving the List edits. This ensures that the server will not time out when saving a large amount of data.

allowboolean: If true, chunked responses will be sent from the server before each operation to save List edits to the data source.

dirtyDetailViewMessagestring

Default = "Cannot synchronize data because Detail View has un-saved changes.". The message shown when you attempt to synchronize a List with a Detail View that has unsaved changes.

fixMediaFileReferencesboolean

Flag fix media file references. For Cordova applications with media files.

pullSyncboolean

Flag that the list should do a pull sync every time a push sync is done.

resetMediaFileUploadErrorsboolean

Can be true or false. If true, file upload media errors will be reset. For Cordova applications with media files.

rowsnumberstringnumber array

The rows to submit. Can explicitly define as number or array of numbers to submit specific rows. Use the string 'current' to specify only the current row should be submitted. Use the string 'allRows' to submit all rows.

Description

Synchronizes edits that have been made to the List (and any of its child Lists).

Discussion

Synchronizes edits that have been made to the List (and any of its child Lists). By default, edits from all dirty rows in the List are submitted to the server. You can optionally specify that just the edits for the currently selected row, or a specified list of rows, should be submitted to the server. You do this by passing in {rows: 'current'} (for just the current or), or {rows: [rowNumber1, rowNumber2, rowNumber3,...] } (for an explicit set of row numbers) in the optional options parameter.

If the List is based on a SQL data source, the data are automatically saved to the table(s) on which the List is based. Alpha Anywhere automatically generates the necessary SQL CRUD statements from the submitted data.

If the List is not based on a SQL data source (for example the Data Source property of the List is set to 'Custom', 'Static', 'Javascript', etc.), then you must write your own synchronization handler to persist the submitted data.

When you submit multiple dirty rows of data you can choose to submit all rows at once, or you can submit data in batches. The batch size can be specified in the List properties, or you can override the setting in List properties by specifying an option in the JSON options passed in as the second parameter to the method. For example:

{dialog.object}.saveListEdits('LISTCUSTOMERS',{rows: 'allRows', batchSize: 10});

When you submit data in batches, the first batch is submitted, then once that batch is synchronized a subsequent callback is triggered to submit the next batch, and so on, until all of the dirty rows have been submitted. The user can cancel before all batches have been submitted. If the user does cancel, the current batch that is being processed will continue to process, but once this batch completes, no further batches will be sent to the server.

Behind the scenes, this method does this:

Calls the List's .harvestList() method to get all of the dirty data to submit to the server
Makes an Ajax callback and submits the List data
Performs server-side validation of the submitted data.
If server-side errors are found, compute the necessary Javascript to return information about the errors to the List so that the Detail View controls can be decorated with the appropriate error messages.
If any write conflicts were found on the server (because another user had edited any of the records that were edited in the List), compute the necessary Javascript to return information about the conflicts to the user so that she may resolve them.
Computes an Ajax response to refresh the rows in the List that were updated and remove the 'dirty' flags from List rows that were previously marked as 'dirty'.

When the List edits are pushed to the server, you can optionally specify that any edits that were made on the server (presumably, by other users) should be pushed back to the List.

When you configure the List control you can set the synchronization policy to control whether 'server-to-client' synching should take place.

Since 'server-to-client' synching is a more expensive operation than 'client-to-server' synching, you might want to turn this option off and instead provide a menu choice to the client to explicitly do a 'server-to-client' synch. To do an explicit 'server-to-client' synch, you can all this method:

{dialog.object}.refreshListData(listId, {mode: 'incremental'});

When you specify the 'incremental' mode any rows in the List that are dirty will not be refreshed.

Synchronizing Data Using pullSync

The synchronization policy for the List can be set to always do a pull sync after pushing data to the server. While this guarantees that any new changes to the data on the server will be downloaded after the client synchronizes local changes, it may not be desireable to always do a pull sync after doing a push. The pullSync property can be used to optionally download changes from the server after local changes have been synchronized. If pullSync is true, a pull sync will be performed regardless of the synchronization policy set in the List control. This lets you pull the latest changes from the server when necessary.

{dialog.object}.saveListEdits('LIST',{rows: 'allRows', pullSync: true});

Example: Setting Request Timeouts and Custom Error Handlers

This example shows how to define a function for the onAjaxFail and onDeviceOffline events.

{dialog.object}.saveListEdits('listName',
{
    rows: 'all' or 'current',
    ajax: {
        timeOut: 15000,
        onAjaxFail: function() { alert('Server could not be reached.'); } ,
        onDeviceOffline: function() { alert('Device is offline.'); }
        }
    });

Example: Defining Custom Callback Functions when saveListEdits fails

The example below shows how to define a callback

{dialog.object}.saveListEdits('LIST1',
    {
        rows: 'allRows',
        chunked: {allow: true},
        ajax: {
            onAjaxFail: function() { alert('Unable to sync.'); } ,
            onDeviceOffline: function() { alert('Unable to sync. Device is offline.'); } ,
            onServerNotAvailable: function() { alert('Unable to sync. Server is not available');}
        }
    }
);

Example: Customizing the Unsaved Changes Message

This example shows how to customize the message shown to the user when synchronization is cancelled because they have unsaved edits.

var msg = "Cannot synchronize now because you have unsaved changes in the Detail View for the current row. Please save or cancel your edits."
var rowsToSync = {dialog.object}.getValue('row_numbers_to_sync').split(',');
{dialog.object}.saveListEdits('list1',{rows: rowsToSync, dirtyDetailViewMessage: msg});